API documentation · v1
Verified talent, one REST call away.
Push briefs from your ATS, pull matches with evidence packs, and subscribe to webhooks for every stage change. OAuth 2.0 or scoped API keys; SSO/SCIM for provisioning.
REST + JSON OAuth 2.0 Webhooks SDKs: JS · Python · Go Sandbox environment
Core endpoints
POST/v1/briefscreate a role brief (or send a JD to interrogate)
GET/v1/briefs/:id/matchesranked matches + evidence packs
POST/v1/matches/:id/interestopen a conversation (candidate consent gate applies)
GET/v1/profiles/:id/shapeverified strengths (anonymised until reveal)
HOOKmatch.stage_changedshortlist → interview → offer → hired
HOOKinvoice.milestone_reachedactivation · shortlist · placement
Rate limits: 600 req/min per org · burst 100 · 429 with Retry-After. Idempotency keys on all POSTs.
quick start — pull matchescurl
curl https://api.suitorly.com/v1/briefs/br_8f2/matches \
  -H "Authorization: Bearer $SUITORLY_KEY"

{
  "data": [{
    "match_id": "mt_4821",
    "fit": 89,
    "shape": "The Untangler",
    "evidence": {
      "strengths_vs_brief": 92,
      "role_screen": 87,
      "peer_confirmed": true
    },
    "status": "recruiter_review",
    "reveal": "pending_candidate_consent"
  }]
}
Consent is enforced in the API
Names, contact details and documents are structurally absent from responses until the candidate's yes — there is no scope that bypasses it.
Sandbox with seeded matches
api.sandbox.suitorly.com ships with briefs, shapes and stage-change simulators so your integration demos without a live mandate.
Changelog
v1.14 — evidence pack PDFs · v1.13 — SCIM 2.0 GA · v1.12 — webhook signing rotated to Ed25519. Breaking changes: 12-month deprecation window.